Cut unnecessary comment content across the engine and observers - #293

Removes 556 comment lines across 9 files. No executable code changes.

Verifying that first, since it is the only thing that matters here

Every changed file was compared token by token against main, with comments and formatting-only tokens stripped:

files changed on this branch: 9
code tokens IDENTICAL in every one: the diff is comments only

So this cannot change behaviour, independent of the suite. The suite is green anyway (2214 passing), along with ruff and pyright.

What was cut, and the test used

The rule is whether a comment describes the code as it stands. Not how it got there, not what it used to do, not the reasoning that produced it.

The dominant pattern, in every one of the nine files, was a real invariant followed by the story of the change that introduced it. The invariant stays, in present tense; the story goes to git. The fan-out tracking key is the clearest example: the key must carry both concurrency axes or two live executions collide and one rolls forward results it never computed. That stays. The account of the branch axis having been absent, and of why nothing surfaced it, does not.

Specifically removed:

• History. What an earlier version did, what a defect used to be, what the engine no longer does.
• Decision provenance. Which coord thread settled a question, "raised for the batched review", "spec ruled".
• Meta-commentary on the comments themselves, including one comment explaining why a previous version of that same comment was wrong.
• Prose duplicating a CHANGELOG entry for the same change, in two copies that had already drifted apart.
• Over-explanation. A 26-line restatement of a keying scheme the code states, numbered walkthroughs of algorithms, proposal-by-proposal change logs on event field docs.

Deliberately kept: every spec citation, and every explanation of a constraint the code currently has to satisfy. Several blocks are still 11-19 lines because they are dense with contract and nothing in them is unnecessary.

Ratios

  cut  file                    ratio
  228  langfuse/observer.py   31.4% -> 25.1%
  127  otel/observer.py       32.0% -> 29.5%
   67  compiled.py            29.4% -> 27.5%
   57  events.py              27.9% -> 24.6%
   27  openai.py              26.0% -> 25.0%
   23  fan_out.py             30.7% -> 29.0%
   17  graph/observer.py      26.8% -> 25.6%
    6  metadata.py            23.3% -> 22.0%
    4  lineage.py             39.2% -> 37.7%

src/ overall moves 23.1% to 21.7%. The ratio barely shifts despite 556 lines going, because the files shrank too, which is the point: these files are long structurally, not merely over-annotated. Closing that gap is the file split, tracked separately and deliberately not attempted during release prep.

Also here

AGENTS.md gains a Docstrings vs # comments section. Docstrings are published through mkdocstrings into docs/reference/, so they are shipped end-user documentation, which is why spec citations and normative language belong in comments instead. That convention governed this sweep and had never been written down.

Not in scope

• A docstring pass. 80 docstrings across 31 files still carry spec refs or normative language; tracked.
• The remaining 36 source files. The mechanically-detectable categories (history, provenance) were swept repo-wide and come back clean; the judgment-based pass covered these nine, and the rest average under 50 narrative lines each.